/*
 * Copyright (c) 1998, 2000, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.accessibility;


import java.util.*;
import java.awt.*;
import javax.swing.text.*;


/**
 * Encapsulation of a link, or set of links (e.g. client side imagemap)
 * in a Hypertext document
 *
 * @author Peter Korn
 * @see Accessible
 * @see Accessible#getAccessibleContext
 * @see AccessibleContext
 * @see AccessibleText
 * @see AccessibleContext#getAccessibleText
 */
public abstract class AccessibleHyperlink implements AccessibleAction {

    /**
     * Since the document a link is associated with may have
     * changed, this method returns whether or not this Link is still valid
     * (with respect to the document it references).
     *
     * @return a flag indicating whether this link is still valid with
     * respect to the AccessibleHypertext it belongs to
     */
    public abstract boolean isValid();

    /**
     * Returns the number of accessible actions available in this Link
     * If there are more than one, the first one is NOT considered the
     * "default" action of this LINK object (e.g. in an HTML imagemap).
     * In general, links will have only one AccessibleAction in them.
     *
     * @return the zero-based number of Actions in this object
     */
    public abstract int getAccessibleActionCount();

    /**
     * Performs the specified Action on the object
     *
     * @param i zero-based index of actions
     * @return true if the action was performed; otherwise false.
     * @see #getAccessibleActionCount
     */
    public abstract boolean doAccessibleAction(int i);

    /**
     * Returns a String description of this particular
     * link action.  This should be a text string
     * associated with anchoring text, this should be the
     * anchor text.  E.g. from HTML:
     * &lt;a HREF="http://www.sun.com/access"&gt;Accessibility&lt;/a&gt;
     * this method would return "Accessibility".
     * <p>
     * Similarly, from this HTML:
     * &lt;a HREF="#top"&gt;&lt;img src="top-hat.gif" alt="top hat"&gt;&lt;/a&gt;
     * this method would return "top hat"
     *
     * @param i zero-based index of the actions
     * @return a String description of the action
     * @see #getAccessibleActionCount
     */
    public abstract String getAccessibleActionDescription(int i);

    /**
     * Returns an object that represents the link action,
     * as appropriate for that link.  E.g. from HTML:
     * &lt;a HREF="http://www.sun.com/access"&gt;Accessibility&lt;/a&gt;
     * this method would return a
     * java.net.URL("http://www.sun.com/access.html");
     *
     * @param i zero-based index of the actions
     * @return an Object representing the hypertext link itself
     * @see #getAccessibleActionCount
     */
    public abstract Object getAccessibleActionObject(int i);

    /**
     * Returns an object that represents the link anchor,
     * as appropriate for that link.  E.g. from HTML:
     * &lt;a href="http://www.sun.com/access"&gt;Accessibility&lt;/a&gt;
     * this method would return a String containing the text:
     * "Accessibility".
     * <p>
     * Similarly, from this HTML:
     * &lt;a HREF="#top"&gt;&lt;img src="top-hat.gif" alt="top hat"&gt;&lt;/a&gt;
     * this might return the object ImageIcon("top-hat.gif", "top hat");
     *
     * @param i zero-based index of the actions
     * @return an Object representing the hypertext anchor
     * @see #getAccessibleActionCount
     */
    public abstract Object getAccessibleActionAnchor(int i);

    /**
     * Gets the index with the hypertext document at which this
     * link begins
     *
     * @return index of start of link
     */
    public abstract int getStartIndex();

    /**
     * Gets the index with the hypertext document at which this
     * link ends
     *
     * @return index of end of link
     */
    public abstract int getEndIndex();
}
